<h1 id="gettingstarted">Getting started</h1>

<h2>Downloading</h2>

<p>Download the source distributable from the
<a href="download.html">Download</a> page.</p>

<h2>Command line tool for testing</h2>

<p>Unpack the distributable:</p>
<pre>
$ cd /tmp
$ tar xvfJ duktape-&lt;version&gt;.tar.xz
</pre>

<p>Compile the command line tool using the provided Makefile:</p>
<pre>
$ cd /tmp/duktape-&lt;version&gt;/
$ make -f Makefile.cmdline
</pre>

<p>The Makefile assumes you have <code>gcc</code> installed.  If you don't,
you can just edit the Makefile to match your compiler (the Makefile is
quite simple).</p>

<div class="note">
Duktape doesn't provide built-in bindings for file or console I/O to avoid
portability issues (for example, some platforms don't have I/O APIs at all).
The command line utility provides <code>print()</code> and <code>alert()</code>
bindings using <a href="https://github.com/svaarala/duktape/blob/master/extras/print-alert">extras/print-alert</a>
to make it easier to play with.  There are useful "extras" in the distributable
providing useful (optional) bindings such as:
<ul>
<li><a href="https://github.com/svaarala/duktape/blob/master/extras/print-alert">print() and alert()</a></li>
<li><a href="https://github.com/svaarala/duktape/blob/master/extras/console">console object, e.g. console.log()</a></li>
</ul>
<b>Throughout the guide examples will assume a <code>print()</code> binding for
illustration.</b>
</div>

<div class="note">
The command line tool avoids platform dependencies by default.  You can add
line editing support via <a href="https://github.com/antirez/linenoise">linenoise</a>
by editing the Makefile:
<ul>
<li>Add <code class="nobreak">-DDUK_CMDLINE_FANCY</code></li>
<li>Add <code>-Ipath/to/linenoise</code> for the <code>linenoise.h</code> header</li>
<li>Add <code>path/to/linenoise.c</code> to the source list</li>
<li>Linenoise only works in POSIX environments and requires a C compiler (not C++)</li>
</ul>
</div>

<p>You can now run ECMAScript code interactively:</p>
<pre>
$ ./duk
((o) Duktape 2.6.0 (v2.6.0)
duk&gt; print('Hello world!')
Hello world!
= undefined
</pre>

<p>You can also run ECMAScript code from a file which is useful for playing with
features and algorithms.  As an example, create <code>fib.js</code>:</p>
<pre class="ecmascript-code" include="fib.js"></pre>

<p>Test the script from the command line:</p>
<pre>
$ ./duk fib.js
0 1 1 2 3 5 8 13 21 34 55 89 144 233 377 610 987 1597 2584 4181
</pre>

<h2>Integrating Duktape into your program</h2>

<p>The command line tool is simply an example of a program which embeds
Duktape.  Embedding Duktape into your program is very simple:</p>

<ul>
<li>Run <code>duktape-N.N.N/tools/configure.py</code> to configure Duktape
    for build.  The result is a directory containing <code>duktape.c</code>,
    <code>duktape.h</code>, and <code>duk_config.h</code>.</li>
<li>Add <code>duktape.c</code>, <code>duktape.h</code>, and <code>duk_config.h</code>
    to your build, and call the Duktape API from elsewhere in your program.</li>
</ul>

<p>The Duktape distributable (duktape-N.N.N.tar.xz) <code>src/</code> directory
contains preconfigured header and source files for the Duktape default configuration
which can usually be used as is.  If needed, the configuration tool allows you to customize
Duktape options, such as optimizing Duktape for low memory targets and
enable/disable features.  See <a href="#compiling">Compiling</a> and
<a href="http://wiki.duktape.org/Configuring.html">Configuring Duktape for build</a>
for more details and examples.</p>

<p>The distributable contains a very simple example program, <code>hello.c</code>,
which illustrates this process.  Compile the test program with the preconfigured
Duktape header and source files e.g. as follows:</p>
<pre>
$ cd /tmp/duktape-&lt;version&gt;/
$ gcc -std=c99 -o hello -Isrc src/duktape.c examples/hello/hello.c -lm
</pre>

<p>To customize Duktape configuration use <code>configure.py</code>:</p>
<pre>
$ cd /tmp/duktape-&lt;version&gt;/
# Here we disable ECMAScript 6 Proxy object support
$ python2 tools/configure.py --output-directory duktape-src -UDUK_USE_ES6_PROXY
$ gcc -std=c99 -o hello -Iduktape-src duktape-src/duktape.c examples/hello/hello.c -lm
</pre>

<p>The test program creates a Duktape context and uses it to run some
ECMAScript code:</p>
<pre>
$ ./hello
Hello world!
2+3=5
</pre>

<p>Because Duktape is an embeddable engine, you don't need to change
the basic control flow of your program.  The basic approach is:</p>
<ul>
<li>Create a Duktape context e.g. in program initialization
    (or even on-demand when scripting is needed).  Usually you
    would also load your scripts during initialization, though
    that can also be done on-demand.</li>
<li>Identify points in your code where you would like to use scripting
    and insert calls to script functions there.</li>
<li>To make a script function call, first push call arguments to the
    Duktape context's <i>value stack</i> using the Duktape API.
    Then, use another Duktape API call to initiate the actual call.</li>
<li>Once script execution is finished, control is returned to your
    program (the API call returns) and a return value is left on the
    Duktape context's value stack.  C code can then access the return
    value using the Duktape API.</li>
</ul>

<p>More broadly, there are several approaches to how you can use Duktape
with native code; for example:</p>
<ul>
<li>Run the main application in C/C++ code but call into Duktape for
    extending base functionality (e.g. plugins or configuration).</li>
<li>Run the main application in ECMAScript code, and call into simple
    C/C++ native bindings for I/O, performance intensive operations, etc.
    The native bindings are often kept stateless so that state logic
    remains in view of script code.</li>
<li>Run the main application in ECMAScript code, but use more complex,
    stateful C/C++ native bindings for performance intensive operations.
    For example, a graphics engine can be implemented as a native object.</li>
</ul>

<p>See the following Wiki articles for detailed examples:</p>

<ul>
<li><a href="http://wiki.duktape.org/GettingStartedLineProcessing.html">Getting started: line processing</a></li>
<li><a href="http://wiki.duktape.org/GettingStartedPrimalityTesting.html">Getting started: primality testing</a></li>
</ul>
